---
title: Pré-carregamento
description: Pré-carregue links para uma navegação mais ágil entre páginas.
i18nReady: true
---

O tempo de carregamento das páginas gera grande impacto na usabilidade e no nível de satisfação de um site. A **opção de pré-carregamento** do Astro traz os benefícios de uma navegação quase instantânea à sua aplicação multi-página (MPA) conforme os seus visitantes interagem com o site.

## Habilitar o pré-carregamento

Você pode habilitar o pré-carregamento com a configuração `prefetch`:

```js title="astro.config.js" ins={4}
import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: true
})
```

Um script de pré-carregamento será adicionado a todas as páginas do seu site. Você pode então adicionar o atributo `data-astro-prefetch` a qualquer link `<a />` do seu site e optar pelo pré-carregamento. Quando você passar o mouse sobre um link, o script irá carregar a página em segundo plano.

```html
<a href="/sobre" data-astro-prefetch>
```

Perceba que o pré-carregamento funciona apenas para links do seu próprio site, e não para links externos.

## Configuração de pré-carregamento

A configuração de `prefetch` também aceita um objeto opcional para customizar o pré-carregamento.

### Estratégias de pré-carregamento

O Astro suporta 4 estratégias de pré-carregamento para diversos casos de uso:

- `hover` (padrão): Pré-carrega quando você passa o mouse sobre o link ou atribui foco a ele.
- `tap`: Pré-carrega logo antes de você clicar no link.
- `viewport`: Pré-carrega assim que os links entrarem na janela de exibição.
- `load`: Pré-carrega todos os links da página assim que ela é carregada.

Você pode especificar uma estratégia para um link individual através do atributo `data-astro-prefetch`:

```html
<a href="/sobre" data-astro-prefetch="tap">Sobre</a>
```

Cada estratégia é ajustada para pré-carregar somente quando necessário e economizar a conexão dos seus usuários. Por exemplo:

- Se um visitante estiver usando o [modo de economia de dados](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) ou possui uma [conexão lenta](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType), o pré-carregamento utilizará a estratégia `tap` como fallback.
- Passar o mouse rapidamente ou rolar a página sobre links não causará o pré-carregamento.
- Links que utilizarem as estratégias `viewport` ou `load` serão pré-carregadas com menor prioridade para evitar gargalo de rede.

### Estratégia padrão de pré-carregamento

A estratégia padrão de pré-carregamento do atributo `data-astro-prefetch` é `hover`. Para alterá-la, você pode configurar o atributo [`prefetch.defaultStrategy`](/pt-br/reference/configuration-reference/#prefetchdefaultstrategy) no seu arquivo `astro.config.js`:

```js title="astro.config.js" ins={4-6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: {
    defaultStrategy: 'viewport'
  }
})
```

### Pré-carregar todos os links por padrão

Se você quiser pré-carregar todos os links, incluindo os que não possuem o atributo `data-astro-prefetch`, você pode configurar [`prefetch.prefetchAll`](/pt-br/reference/configuration-reference/#prefetchprefetchall) para `true`:

```js title="astro.config.js" ins={4-6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: {
    prefetchAll: true
  }
})
```

Você pode, então, escolher não pré-carregar links individualmente adicionando `data-astro-prefetch="false"`:

```html
<a href="/sobre" data-astro-prefetch="false">Sobre</a>
```

A estratégia de pré-carregamento padrão pode ser alterada para todos os links com `prefetch.defaultStrategy`, como foi mostrado na [seção Estratégia padrão de pré-carregamento](#estratégia-padrão-de-pré-carregamento).

## Pré-carregar programaticamente

Como nem sempre a navegação será exibida na forma de links `<a />`, você pode também pré-carregar páginas programaticamente com a API `prefetch()` do módulo `astro:prefetch`:

```astro
<button id="botao">Clique aqui</button>

<script>
  import { prefetch } from 'astro:prefetch';

  const botao = document.getElementById('botao');
  botao.addEventListener('click', () => {
    prefetch('/sobre');
  });
</script>
```

Você pode também configurar a prioridade de pré-carregamento através da opção `with`:

```js
// Pré-carregamento com `fetch()` possui prioridade mais alta.
prefetch('/sobre', { with: 'fetch' });

// Pré-carregamento com `<link rel="prefetch">` possui prioridade mais baixa
// e é manualmente agendada pelo navegador. (padrão)
prefetch('/sobre', { with: 'link' });
```

A API `prefetch()` inclui as mesmas detecções de [modo de economia de dados](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) e [de conexão lenta](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType) de forma que o pré-carregamento ocorra apenas quando é necessário.

Para ignorar a detecção de conexão lenta, você pode utilizar a opção `ignoreSlowConnection`:

```js
// Pré-carrega mesmo no modo de economia de dados ou conexão lenta
prefetch('/sobre', { ignoreSlowConnection: true });
```

Tome o cuidado de apenas utilizar o `prefetch()` em scripts do lado do cliente, pois ele depende das APIs do navegador para funcionar.

## Utilizando com Transições de Visualização

Quando você usa [Transições de Visualização](/pt-br/guides/view-transitions/) em uma página, o pré-carregamento também será habilitado por padrão. Isso configura o atributo `{ prefetchAll: true }`, que habilita o [pré-carregamento para todos os links](#pré-carregar-todos-os-links-por-padrão) da página.

Você pode customizar a configuração de pré-carregamento no arquivo `astro.config.js` para sobrescrever a configuração padrão. Por exemplo:

```js title="astro.config.js"
import { defineConfig } from 'astro/config';

export default defineConfig({
  // Desabilita o pré-carregamento completamente
  prefetch: false
})
```

```js title="astro.config.js"
import { defineConfig } from 'astro/config';

export default defineConfig({
  // Mantém o pré-carregamento, mas pré-carrega apenas links com `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
})
```

## Migrando de `@astrojs/prefetch`

A integração `@astrojs/prefetch` foi descontinuada na versão v3.5.0 e eventualmente será removida completamente. Siga as seguintes instruções para migrar para o pré-carregamento integrado do Astro, que substitui essa integração.

1. Remova a integração `@astrojs/prefetch` e habilite a configuração `prefetch` em `astro.config.js`:

    ```js title="astro.config.js" ins={6} del={2,5}
    import { defineConfig } from 'astro/config';
    import prefetch from '@astrojs/prefetch';

    export default defineConfig({
      integrations: [prefetch()],
      prefetch: true
    })
    ```

2. Converta as opções de configuração do `@astro/prefetch`:

    - A integração descontinuada utilizava a opção de configuração `selector` para especificar quais links deveriam ser pré-carregados quando entrassem na janela de exibição (viewport).

      Ao invés disso, adicione `data-astro-prefetch="viewport"` a esses links individualmente:

      ```html
      <a href="/sobre" data-astro-prefetch="viewport">
      ```

    - A integração descontinuada utilizava a opção de configuração `intentSelector` para especificar quais links deveriam ser pré-carregados quando o usuário passasse o mouse sobre ele, ou entrasse em foco.

      Ao invés disso, adicione `data-astro-prefetch` ou `data-astro-prefetch="hover"` a esses links individualmente:

      ```html
      <!-- Você pode omitir o valor se `defaultStrategy` estiver configurado como `hover` (padrão) -->
      <a href="/sobre" data-astro-prefetch>

      <!-- Caso contrário, você pode definir explicitamente a estratégia de pré-carregamento -->
      <a href="/sobre" data-astro-prefetch="hover">
      ```

    - A opção `throttles` do `@astrojs/prefetch` não é mais necessária, pois o novo recurso de pré-carregamento irá automaticamente agendar e pré-carregar de forma otimizada.
